…algorithm-csharp into develop/1.0

…algorithm-csharp into develop/1.0

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <me@petesramek.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <me@petesramek.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

…algorithm-csharp into develop/1.0

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <me@petesramek.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <me@petesramek.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

…algorithm-csharp into develop/1.0

…#158)

`administration` is not a valid scope for the GitHub Actions
`permissions` key, causing a workflow parse failure before any jobs run.

## Change

- Removed `administration: write` from the top-level `permissions` block
in `.github/workflows/release.yml`

The branch-protection lock action already passes `github.token` directly
to `gh api`, so no additional workflow-level permission entry is needed
or valid here.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <2333452+petesramek@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…rhaul (#159)

## Overview

Promotes `develop/1.0` to `preview/1.0` in preparation for the 1.0
preview release. This batch brings in a full rewrite of the library's
core, docs, CI/CD pipeline, and test suite accumulated since the last
preview snapshot.

## What's included

### 🏗️ CI/CD & Workflows
- **New workflows**: `bump-version`, `promote-branch` with source-branch
enforcement, auto merge-to-main on release
- **Branch protection**: new `lock`/`unlock` composite actions;
`preview/**` and `release/**` branches are now automatically locked
after creation
- **Fix**: removed invalid `administration` permission from
`release.yml` that caused workflow parse failures (#158)
- **Fix**: corrected pull-request-finding logic in promote workflow
- **Docs publishing**: URL-aware version switcher via `docs-versioning`
template; `versions.json` manifest; reworked `generate-docs` job (#157)

### 📚 Documentation
- New `/docs` developer guides: local development, testing conventions,
benchmarks, composite actions catalogue, CI workflow reference, branch
strategy, versioning pipeline, API doc generation, extensibility guide
(#155)
- Updated API reference YAMLs for version 1.0
- Fixed grammar, TOC typo, and outdated API references in docs
- Updated `CONTRIBUTING.md` with links to all new docs articles
- Flushed `PublicAPI.Unshipped.txt`

### 🔧 Source (library)
- Refactored internal structure: `CoordinateDelta`,
`CoordinateVariance`, `Pow10`, `Defaults`, `ExceptionGuard`, logging
helpers
- Updated `PolylineEncoder`, `PolylineDecoder`, `PolylineEncoding`,
`PolylineEncodingOptions`, `PolylineEncodingOptionsBuilder`
- Public API cleanup; `.editorconfig` updated (primary constructors
disabled)

### ✅ Tests
- Reorganized test files into proper namespace folders (`Abstraction/`,
`Extensions/`, `Internal/`)
- Added new test classes for `CoordinateDelta`, `CoordinateVariance`,
`Pow10`, `ExceptionGuard`, `LogDebugExtensions`, `LogWarningExtensions`,
`InvalidPolylineException`, `PolylineEncodingOptionsBuilder`, and
encoder/decoder extensions
- Removed stale/duplicate test files

### 🛠️ Build & Config
- Cleaned up `PolylineAlgorithm.slnx`, `Directory.Build.props`,
benchmarks config
- Updated `.gitignore` to exclude dynamically generated
`api-reference/_docs/`
- Misc cleanup (removed junk files, updated `AGENTS.md`)

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

- Removed administration permission

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

- Removed administration permission

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…flow (#162)

`git switch <base-branch>` in the "Create target branch" step replaced
the workspace with the base branch contents. Since `main` doesn't carry
the composite actions, the immediately following `Lock target branch`
step couldn't resolve `action.yml`.

## Change

- **`promote-branch.yml`** — replaced the `git switch` + `git checkout
-b` + `git push` sequence with a single refspec push:
  ```sh
  git fetch origin
  git push origin origin/<base-branch>:refs/heads/<target-branch>
  ```
Creates the remote branch from the base ref without touching the local
workspace, so the source branch's composite actions remain accessible
for subsequent steps.

## Side effect to handle

`release/1.0` was already created by the failed run (off `main`,
unprotected). After this fix lands on `preview/1.0`, delete
`release/1.0` and re-run `promote-branch` to get a correctly locked
branch.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…164)

`GITHUB_TOKEN` cannot call the Branch Protection API (`PUT/DELETE
.../protection`) — it always returns `403`. Repository admin access
requires a PAT.

## Changes

- **`lock/action.yml`, `unlock/action.yml`**: Added required `token`
input; replaced hardcoded `github.token` with `inputs.token`
- **`promote-branch.yml`, `release.yml`**: Pass `secrets.GH_ADMIN_TOKEN`
to the `token` input of the lock step

## Required Setup

Create a repository secret `GH_ADMIN_TOKEN` containing a PAT (classic
with `repo` scope, or fine-grained with **Administration: Read &
Write**) belonging to a repo admin.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <2333452+petesramek@users.noreply.github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Pete Sramek <petr.sramek@dropoutcoder.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…flow (#167)

The "Create release" job fails with exit code 127 due to two bugs in the
`Determine notes start tag` step.

## Root Causes

- **Invalid bash variable name**: `notes-start-tag=$(git describe ...)`
— hyphens are illegal in bash variable names. Bash interprets
`notes-start-tag=` as a command, not an assignment.
- **`git describe` fails with no tags**: `actions/checkout` defaults to
`fetch-tags: false`, so `git describe --abbrev=0 --tags` exits non-zero;
with `-e` / `pipefail` active, this kills the step.

## Changes

- **`release.yml` — `release` job, checkout step**: Added `fetch-tags:
true` so prior tags are available to `git describe`.
- **`release.yml` — `Determine notes start tag` step**: Renamed bash
variable to `notes_start_tag` (underscores); added `2>/dev/null || echo
""` to gracefully handle repos with no prior tags. The `GITHUB_OUTPUT`
key `notes-start-tag` is unchanged.

```bash
# Before (broken)
notes-start-tag=$(git describe --abbrev=0 --tags)
echo "notes-start-tag=$notes-start-tag" >> $GITHUB_OUTPUT

# After
notes_start_tag=$(git describe --abbrev=0 --tags 2>/dev/null || echo "")
echo "notes-start-tag=$notes_start_tag" >> $GITHUB_OUTPUT
```

The `create-release` action already treats an empty `notes-start-tag` as
a no-op, so the fallback is safe.

…on discovery (#168)

The "Discover all versions" step in `publish-documentation.yml` used
`\d` in grep ERE patterns, which is not supported in POSIX ERE on Ubuntu
24.04. This caused `grep` to return exit code 1 (no matches), failing
the step under `pipefail`.

## Change
- Replace `\d` with `[0-9]` in both grep patterns in the `Discover all
versions` step:

```diff
- versions=$(ls api-reference/ | grep -E '^\d+\.\d+$' | sort -V | paste -sd ',' -)
- latest=$(ls api-reference/ | grep -E '^\d+\.\d+$' | sort -V | tail -1)
+ versions=$(ls api-reference/ | grep -E '^[0-9]+\.[0-9]+$' | sort -V | paste -sd ',' -)
+ latest=$(ls api-reference/ | grep -E '^[0-9]+\.[0-9]+$' | sort -V | tail -1)
```

`\d` requires `grep -P` (PCRE); POSIX ERE (`-E`) only recognises
`[0-9]`.

…to-trigger (#169)

`publish-documentation.yml` was firing automatically on every push to
`release/**`, running independently from `release.yml` and outside the
controlled release pipeline.

## Changes

**`publish-documentation.yml`**
- Replaced `push` trigger with `workflow_call` — workflow is now
exclusively driven by `release.yml` or manual dispatch
- `workflow_dispatch` retained for on-demand runs

**`release.yml`**
- Added `publish-documentation` job between `pack` and
`publish-package`:
  - Depends on `pack` + `validate-release`
- Gated with `if: is-release == 'true'` — skipped on `preview/**`
branches
- Calls `./.github/workflows/publish-documentation.yml` with explicit
`pages: write` + `id-token: write` permissions
- Updated `publish-package` to depend on `publish-documentation` with an
`always()`-based condition to handle the `skipped` result on preview
branches, preventing the gate from blocking NuGet publishing:

```yaml
publish-package:
  needs: [pack, validate-release, publish-documentation]
  if: >-
    always() &&
    needs.pack.result == 'success' &&
    needs.validate-release.result == 'success' &&
    (needs.publish-documentation.result == 'success' || needs.publish-documentation.result == 'skipped')
```

…add released versions table (#175)

## Summary

Previously, versioned folders contained only API reference YAMLs while
guide pages were global (unversioned). The root `index.md` had entirely
broken links. The version switcher navigated to a bare `/{ver}/` folder
that has no `index.html`, causing 404s on GitHub Pages.

## Changes

### Workflow (`publish-documentation.yml`)
- **Guide snapshot**: copies `api-reference/guide/` into
`api-reference/{ver}/guide/` immediately after API metadata generation,
so each version folder contains a full snapshot of both guide and API
reference
- **DocFX version groups**: each group now registers two content entries
— API YAMLs (`*.yml`) and guide pages (`guide/*.{md,yml}`) — producing
`_docs/{ver}/` and `_docs/{ver}/guide/` in the build output
- **Global TOC**: `Guide` nav link now points to
`{latest}/guide/introduction.html` instead of the unversioned `guide/`
- **index.md injection**: a single step builds the released versions
table and substitutes both `{version}` and `{versions_section}`
placeholders before `docfx build` runs (no committed artefacts)

### `api-reference/api-reference.json`
- Removed `guide/*.{md,yml}` from the global content entry — guide pages
now exist only within versioned groups

### `api-reference/index.md`
- Replaced broken links with `{version}`-placeholder paths resolved at
build time
- Added a `{versions_section}` placeholder that the workflow expands
into a full released-versions table

### `docs-versioning/public/version-switcher.js`
- Fixed the fallback navigation branch to resolve the site root via the
`docfx:rel` meta tag and navigate to `/{ver}/PolylineAlgorithm.html`
instead of the bare `/{ver}/` folder